home *** CD-ROM | disk | FTP | other *** search
/ Windows Game Programming for Dummies (2nd Edition) / WinGamProgFD.iso / pc / DirectX SDK / DXSDK / samples / Multimedia / DirectPlay / ChatPeer / readme.txt < prev    next >
Encoding:
Text File  |  2001-10-10  |  5.0 KB  |  96 lines
  1. //-----------------------------------------------------------------------------
  2. // 
  3. // Sample Name: ChatPeer Sample
  4. // 
  5. // Copyright (c) 1999-2001 Microsoft Corporation. All rights reserved.
  6. // 
  7. //-----------------------------------------------------------------------------
  8.  
  9.  
  10. Description
  11. ===========
  12.   ChatPeer is similar in form to SimplePeer.  Once a player hosts or connects
  13.   to a session, the players can chat with either other by passing text 
  14.   strings.
  15.   
  16. Path
  17. ====
  18.   Source: DXSDK\Samples\Multimedia\DirectPlay\ChatPeer 
  19.  
  20.   Executable: DXSDK\Samples\Multimedia\DirectPlay\Bin
  21.  
  22. User's Guide
  23. ============
  24.   Refer to User's Guide section of the SimplePeer sample.
  25.  
  26. Programming Notes
  27. =================
  28.   The ChatPeer sample is very similar in form to the SimplePeer sample.  For 
  29.   detailed programming notes on the basics this sample, refer to Programming 
  30.   Notes section of the SimplePeer sample.
  31.  
  32.   The ChatPeer differs by letting clients send text strings to all players
  33.   connected to the session.
  34.   
  35.   * The "Send" button is pressed.  See SendChatMessage().
  36.         1. Retrieves the text string from the dialog.
  37.         2. Fills a app defined struct, GAMEMSG_CHAT.  This struct has
  38.            a message type ID as the first BYTE.  This lets our app
  39.            figure out what type of app message they received, however 
  40.            ChatPeer only uses one app defined message. See StagedPeer
  41.            for a more complex example of this process.
  42.         3. Fills out a DPN_BUFFER_DESC struct using the GAMEMSG_CHAT buffer.
  43.         4. Calls IDirectPlay8Peer::SendTo() with the DPN_BUFFER_DESC.  It passes 
  44.            DPNID_ALL_PLAYERS_GROUP so this message goes to everyone. 
  45.    
  46.   * Handle DirectPlay system messages.  See DirectPlayMessageHandler()
  47.  
  48.         The ChatPeer handles the typical messages as described in the 
  49.         SimplePeer programming notes, and in addition:
  50.         
  51.         - Upon DPN_MSGID_RECEIVE message:         
  52.            1. It casts pReceiveMsg->pReceiveData into a generic app defined 
  53.               structure, GAMEMSG_GENERIC.  This helps to figure out what structure 
  54.               is really contained in pReceiveMsg->pReceiveData. For this simple 
  55.               example, if the ID is GAME_MSGID_CHAT it casts the buffer to a 
  56.               GAMEMSG_CHAT*.              
  57.            2. It then creates a new APP_QUEUED_DATA struct which contains a pointer 
  58.               to the GAMEMSG_CHAT buffer, and the a DirectPlay handle linked to the 
  59.               GAMEMSG_CHAT buffer.  
  60.            3. We then post a user defined message, WM_APP_CHAT, to the dialog thread 
  61.               with the lParam equal to a pointer to the APP_QUEUED_DATA struct and
  62.               the wParam equal to the DPNID of the player who sent us the buffer.
  63.               We post a message since this lets us return from the DirectPlay message
  64.               handler quickly.  In a complex game if the handler threads take too 
  65.               long its possible that a backlog of network data may arise.
  66.            4. We return from DirectPlayMessageHandler() with the result code 
  67.               of DPNSUCCESS_PENDING.  This error code tells DirectPlay that the buffer 
  68.               we got in the DPN_MSGID_RECEIVE message is still in use by our app.  
  69.               This allows us to not to have to copy the buffer, but instead pass a 
  70.               pointer of it off to a worker thread.  This simple sample just uses 
  71.               the main dialog thread to process queued data.  For a more complex 
  72.               example of this process see the DataRelay sample.
  73.             
  74.   * Upon receiving WM_APP_CHAT in the message loop
  75.         This is posted to the message loop by one DirectPlay message handler threads
  76.         whenever we receive a chat message.  See above for more detail.  Here's what 
  77.         happens:
  78.         
  79.         1. Cast the wParam to a DPNID.  This is the player that sent the message. 
  80.         2. Calls IDirectPlay8Peer::GetPlayerContext().  This retrieves a user 
  81.            specified pointer (which we cast to a APP_PLAYER_INFO*) associated with 
  82.            this player.  See the SimplePeer programming notes for more info on how 
  83.            this is setup.  Also, note that since player can be deleted at any time, 
  84.            we need to use ref counting to make sure this player context struct isn't 
  85.            deleted while we are still using it.  
  86.         3. Cast the lParam into a APP_QUEUED_DATA*.  This tells us the buffer, and the DirectPlay
  87.            handle associated with that buffer.
  88.         4. Process the buffer by adding it's text string to the dialog.
  89.         5. Release the APP_PLAYER_INFO* since we are done using it.
  90.         6. Now DirectPlay can free the receive buffer since we are done with it.  
  91.            So return the buffer to DirectPlay by calling IDirectPlay8Peer::ReturnBuffer, 
  92.            passing in the DirectPlay buffer handle.  
  93.         7. Deletes the APP_QUEUED_DATA from the heap
  94.         
  95.                 
  96.